Node / ReticulumProjects / MeshChatX.git / files / vendor / lxmfy / docs / source / quick-start.rst

Displaying Raw • Download

Tc9d1d9Quick Start

Tc9d1d9===========

Tc9d1d9Prerequisites

Tc9d1d9-------------

T79c0ff* Python 3.11+

T79c0ff* Reticulum Network Stack (Te6edf3:code:Te6edf3`pip install rns`)

T79c0ff* LXMFy (Te6edf3:code:Te6edf3`pip install lxmfy` or install from source)

Tc9d1d9Creating Your First Bot (Using the CLI)

Tc9d1d9----------------------------------------

The easiest way to start is using the LXMFy command-line tool.

T79c0ff1. **Open your terminal** in the directory where you want to create your bot project.

T79c0ff2. **Run the create command:**

Tb4b4b4 .. Tff7b72code-blockTb4b4b4:: Tff7b72bash

lxmfy create my_first_bot

This command will generate the following files:

T79c0ff* Te6edf3:code:Te6edf3`my_first_bot.py`: Your main bot file, configured with sensible defaults.

T79c0ff* Te6edf3:code:Te6edf3`cogs/`: A directory for bot extensions (cogs).

T79c0ff* Te6edf3:code:Te6edf3`cogs/__init__.py`: Makes the Te6edf3:code:Te6edf3`cogs` directory a Python package.

T79c0ff* Te6edf3:code:Te6edf3`cogs/basic.py`: An example cog with simple "hello" and "about" commands.

T79c0ff* Te6edf3:code:Te6edf3`data/`: A directory where the bot will store its data (using JSON by default).

T79c0ff* Te6edf3:code:Te6edf3`config/`: A directory where the bot stores its identity and announce status.

T79c0ff3. **Review the :code:`my_first_bot.py` file:**

Tb4b4b4 .. Tff7b72code-blockTb4b4b4:: Tff7b72python

Tff7b72from T7ee787lxmfy Tff7b72import Te6edf3LXMFBot

Te6edf3bot Tff7b72= Te6edf3LXMFBotTb4b4b4(

name="my_first_bot", # Bot name used in announces/identity

announce=600, # Announce interval in seconds (10 minutes)

announce_immediately=True, # Announce on first run?

admins=set(), # Set of admin LXMF address hashes

hot_reloading=False, # Enable/disable hot reloading of cogs

rate_limit=5, # Max messages per minute per user

cooldown=60, # Cooldown period in seconds for rate limit

max_warnings=3, # Warnings before ban for spam

warning_timeout=300, # Time (seconds) before warnings reset

command_prefix="/", # Prefix for commands (e.g., /hello)

cogs_dir="cogs", # Directory to load cogs from

cogs_enabled=True, # Enable/disable loading cogs

permissions_enabled=False, # Enable/disable the role-based permission system

storage_type="json", # Storage backend ("json", "sqlite", or "memory")

storage_path="data", # Path for storage files/database

first_message_enabled=True, # Enable special handling for first messages

event_logging_enabled=True, # Log events to storage?

max_logged_events=1000, # Max events to keep in log

event_middleware_enabled=True, # Enable event middleware?

announce_enabled=True, # Enable/disable network announces

signature_verification_enabled=False, # Enable/disable cryptographic signature verification

require_message_signatures=False # Require all messages to be signed

)

# To add an admin, find your LXMF address hash and add it here:

# bot.config.admins.add("your_lxmf_hash_here")

# bot.admins = bot.config.admins # Ensure the running instance knows

# Example of preparing an LXMF icon field (optional)

# from lxmfy import IconAppearance, pack_icon_appearance_field

# try:

# icon_data = IconAppearance(icon_name="emoji_objects", fg_color=b'\xFF\xA5\x00', bg_color=b'\x8B\x45\x13') # Orange on Brown

# bot.icon_field = pack_icon_appearance_field(icon_data) # Store for use in send/reply

# except Exception as e:

# print(f"Could not prepare icon field: {e}")

# bot.icon_field = None

if __name__ == "__main__":

print(f"Starting bot: {bot.config.name}")

print(f"Bot LXMF Address: {bot.local.hash}") # Prints the bot's address

bot.run()

T79c0ff4. **(Optional) Add Your Admin Hash:**

T79c0ff* Find your LXMF address hash (e.g., from your Reticulum client like Sideband or NomadNet).

T79c0ff* Uncomment and edit the Te6edf3:code:Te6edf3`bot.config.admins.add(...)` line in Te6edf3:code:Te6edf3`my_first_bot.py`, replacing Te6edf3:code:Te6edf3`"your_lxmf_hash_here"` with your actual hash.

T79c0ff5. **Run Your Bot:**

Tb4b4b4 .. Tff7b72code-blockTb4b4b4:: Tff7b72bash

python my_first_bot.py

Your bot will start, print its LXMF address, potentially send an announce message over the Reticulum network, and begin listening for messages.

Tc9d1d9Interacting With Your Bot

Tc9d1d9-------------------------

T79c0ff1. **Send a message** to the bot's LXMF address from your client.

T79c0ff2. **Try the example command:** Send Te6edf3:code:Te6edf3`/hello` to the bot. It should reply with "Hello Te6edf3:code:Te6edf3`<your_hash>`!".

If you uncommented the icon example above, this reply might also carry an icon.

T79c0ff3. **Try the help command:** Send Te6edf3:code:Te6edf3`/help`.

Tc9d1d9Advanced Features

Tc9d1d9-----------------

Once you're comfortable with the basics, explore these advanced features:

**Message Handlers:**

T79c0ff* Use Te6edf3:code:Te6edf3`@bot.on_first_message()` to welcome new users

T79c0ff* Use Te6edf3:code:Te6edf3`@bot.on_message()` to handle all messages before command processing

**Reliable Delivery:**

T79c0ff* Configure Te6edf3:code:Te6edf3`direct_delivery_retries` in Te6edf3:code:Te6edf3`LXMFBot(...)` for automatic retry before propagation fallback

T79c0ff* Configure Te6edf3:code:Te6edf3`propagation_node` in bot config (or use Te6edf3:code:Te6edf3`bot.set_propagation_node(...)`) to route through a specific LXMF propagation node

**Security:**

T79c0ff* Enable Te6edf3:code:Te6edf3`signature_verification_enabled=True` to enforce LXMF's built-in signature verification

T79c0ff* Set Te6edf3:code:Te6edf3`require_message_signatures=True` to reject unsigned or invalid messages

T79c0ff* Note: LXMF automatically signs all messages; LXMFy just enforces verification policy

See the Ta5d6ff`Creating Bots Tffd700<creating-bots.html>Ta5d6ff`_ guide and Ta5d6ff`API Reference Tffd700<api-reference.html>Ta5d6ff`_ for detailed information on these features.

Tc9d1d9Next Steps

Tc9d1d9----------

T79c0ff* Explore the Ta5d6ff`Creating Bots Tffd700<creating-bots.html>Ta5d6ff`_ guide for more details on adding commands, using cogs, and different bot types.

T79c0ff* Check the Ta5d6ff`API Reference Tffd700<api-reference.html>Ta5d6ff`_ for detailed information on framework components.